home *** CD-ROM | disk | FTP | other *** search
/ Sound Fx / Sound Fx.iso / Software / UNZIPED / DWSTK / READ.ME < prev    next >
Text File  |  1996-10-18  |  17KB  |  469 lines
  1. READ.ME was finalized on 10/18/96 for v2.22 of DiamondWare's Sound ToolKit.
  2.  
  3.  
  4.  
  5. ================================
  6. How to use the STK documentation
  7. ================================
  8.  
  9. The complete STK documentation comes either in the file STKMAN.DOC (for the
  10. shareware version), or in a printed book for the registered version.
  11.  
  12. A product like the Sound ToolKit is a complicated beast.  We can't
  13. overemphasize the importance of reading the documentation.  There are many
  14. caveats, and subtle ways to improve the performance of your application in
  15. the docs.  We didn't go to all the effort of writing, just so everyone
  16. wouldn't read it! <g>
  17.  
  18. Also, we provide source code to several sample programs, which you'll
  19. definitely want to read over.
  20.  
  21. READ.ME is a supplement to the complete STK docs.
  22.  
  23. As we update the STK, we update the documentation.  Such updates will
  24. always be appended to this file, as well as inserted into STKMAN.DOC where
  25. appropriate.  You'll save a lot of time by reading this file rather than
  26. hunting through STKMAN.DOC for changes.  Just skip down to the section
  27. which covers the version after the one with which you're familiar, and read
  28. until the end of the file.
  29.  
  30. The printed manual will be updated less frequently (for major versions,
  31. and whenever we reprint).  This file will tell you what's new since the
  32. last printing.
  33.  
  34. Currently, the printed manual is mostly up to date (up to v2.00), but does
  35. not discuss the new DSP code, a new VOC2DWD command-line option, or the new
  36. Borland Pascal protected-mode support.    And there are two corrections also.
  37. If you have the registered version with the printed manual, go to line 287.
  38.  
  39.  
  40.  
  41. ==============================
  42. If you're upgrading from v1.00
  43. ==============================
  44.  
  45. Improvements
  46. ------------
  47.  
  48. The API did not change, and no working code was broken.
  49.  
  50.  
  51.   o  The STK now allows re-entrancy.
  52.  
  53.   o  dws_DetectHardWare checks the BLASTER environment variable.
  54.  
  55.   o  The bass drum is louder, deeper, and punchier.
  56.  
  57.   o  The STK checks the interrupt flag before some STK functions.
  58.  
  59.   o  We added OPLKBD.EXE (registered version only).
  60.  
  61.   o  The music playback is now more sensitive to note velocities.
  62.  
  63.  
  64. You can now call any STK function from any background task, including an ISR.
  65. If the STK can't deal with the call right then, it will return a (new) error.
  66. dws_BUSY means that you should call again later (your next timer tick, or
  67. some other soon time).  IF YOU'RE CALLING THE STK ONLY FROM THE FOREGROUND,
  68. THIS ERROR CANNOT OCCUR.
  69.  
  70. PLAYDWM and PLAYDWD have been updated to show detection of this new error
  71. condition (although neither program can actually generate it).
  72.  
  73. dws_DetectHardWare now uses the BLASTER environment variable to help it find
  74. sound boards.  It looks for the sound board's port at the address specified
  75. in the BLASTER variable.  It will also use the BLASTER's IRQ and DMA settings
  76. as a last resort--if it's unable to find them from examining the hardware.
  77.  
  78. When you call dws_DetectHardWare, dws_Init, or dws_Kill, interrupts must
  79. be enabled.  If they're not, you'll get a (new) error.  dws_IRQDISABLED means
  80. that IRQs are disabled--but in order to work properly, the STK function you
  81. just called requires them to be _enabled_.  This error shouldn't occur,
  82. unless you're developing interrupt service routines, and other non-mainstream
  83. code.
  84.  
  85. For registered users, we added a new program: OPLKBD.EXE.  This allows you
  86. to load an .IBK file, and "play" notes from it on your 101 keyboard (including
  87. polyphony.)  It's useful for tweaking .IBK files.
  88.  
  89.  
  90.  
  91. Bugs Fixed
  92. ----------
  93.  
  94.   o  MID2DWM.EXE no longer requires an FPU.
  95.  
  96.   o  Some "clickiness" in music playback was eliminated.
  97.  
  98.   o  SB16 mixer settings now restored properly upon dws_Kill.
  99.  
  100.   o  Sequencing sounds no longer causes the STK to enter a bad state.
  101.  
  102.   o  dres.baseport is set even if dws_DetectHardWare can't find IRQ or DMA.
  103.  
  104.   o  On Windows Sound System, under Windows, dws_DetectHardWare now works.
  105.  
  106.   o  Inside the STK, interrupts are disabled where necessary.
  107.  
  108.   o  dws_Kill is slightly quiter.
  109.  
  110.   o  FM chip reset is more complete.
  111.  
  112.   o  Obscure change instrument bug fixed.
  113.  
  114.   o  On OPTI chipset boards (MAD16), mixer and autodetect now work better.
  115.  
  116.   o  Auto-initialized DMA mode is used whenever supported by the hardware.
  117.  
  118.  
  119. Because we're using auto-init DMA mode (don't worry if you don't know what
  120. this means--it's a detail within the STK), dws_DSetRate makes some noise
  121. on some sound boards.  We recommend (though don't require) that you change
  122. rates during periods of silence.
  123.  
  124.  
  125.  
  126. Additional Docs
  127. ---------------
  128.  
  129. We wrote this addendum to address common questions raised by users.
  130.  
  131.  
  132. The STK music playback engine may behave differently than you'd expect.  The
  133. following is a brief discussion of two bona fide features which may cause
  134. some unexpected problems.
  135.  
  136. The STK is extremely sensitive to velocity.  If you play a song and the
  137. drums or an instrument sound faint (or loud), this is why.  Change the
  138. output level of the instrument patch, or use your sequencer to bring up
  139. the volume of the problem track.
  140.  
  141. The STK will allow notes of bells and strings to "ring out" after they are
  142. "key released".  If this is causing undesired effects, simply make your
  143. instrument patches "sustaining".  The STK will shut such notes down
  144. immediately when they are released.
  145.  
  146.  
  147. Finding the user's sound board is non-trivial, because the user often
  148. doesn't even know what brand he owns, let alone its settings.  So the STK
  149. asks the hardware directly.
  150.  
  151. It does a good job, but there are some potential problems.  Sometimes, the
  152. STK may be unable to find one or more sound hardware parameters (almost
  153. always the problem lies with finding the DMA channel).
  154.  
  155. The capability field in the dws_DETECTRESULTS struct will tell you if the
  156. STK found everything it needed for music and for digitized.  If both
  157. capability flags are set, then you have nothing further to do; music and
  158. sound will work.
  159.  
  160. However, only the dws_capability_FM flag might be set.  This may be because
  161. the user has music-only hardware, or it may be that (for example) the STK
  162. was unable to find the DMA channel.  To tell the difference, look at the
  163. baseport field of the dws_DETECTRESULTS struct.  If this field returns as
  164. either 65535 or 388h, this means that no digitized-capable sound hardware
  165. is present (or the user's drivers aren't installed).  If this field returns
  166. with any other value, it means that digitized hardware exists.  Look at the
  167. digirq and digdma fields.  If either or both of these are set to 65535, it
  168. means that the STK couldn't autodetect them (and the BLASTER environment
  169. variable was either not present, or was wrong).
  170.  
  171. Planning ahead for this, you should have a screen where the user can type in
  172. port, DMA, and IRQ channel.  Don't require him to do this, but make this
  173. option available.  Take the settings you are given, and plug them into the
  174. dws_OVERRIDES struct.  Then call dws_DetectHardWare again.
  175.  
  176. Don't simply look at the capability field of the dws_DETECTRESULTS.  Its
  177. boolean flags simply indicate whether or not we figured out everything we
  178. needed to know about music and digitized sound.  It can't tell you, for
  179. example, if we have a port and an IRQ level, but no DMA channel.  To
  180. determine this, look at the baseport, digdma, and digirq fields.  If baseport
  181. is 65535 (or 388h), then we found no digitized capability.  It's virtually
  182. certain that none is present.  If baseport is 220h, digdma is 65535 and
  183. digirq is 7, then we couldn't determine the DMA channel.  Ask the user!  It
  184. beats dimming out your sound option.
  185.  
  186. We provide a new example program to registered users: SETUP.C, which handles
  187. setup of sound settings, and configuration files.  It isn't pretty (using
  188. just printf and scanf), but it illustrates some important concepts.
  189.  
  190.  
  191.  
  192. ==============================
  193. If you're upgrading from v1.02
  194. ==============================
  195.  
  196. Improvements
  197. ------------
  198.  
  199. The API did not change, and no working code was broken.
  200.  
  201.  
  202.   o  err.h is now compatible with C++ (the way dws.h and dwt.h were).
  203.  
  204.   o  On SB16's, IRQ 2/9 is handled more efficiently.
  205.  
  206.   o  SETUP.C was significantly revamped.
  207.  
  208.  
  209. Changes
  210. -------
  211.  
  212.   o  The typedef for word was changed from unsigned int to unsigned short.
  213.  
  214.   o  All dws_ and dwt_ functions load DS properly.
  215.  
  216.   o  _loadds and _saveregs keywords were removed from dws_Update, though it
  217.      still loads DS and saves all registers.
  218.  
  219.  
  220. Bugs Fixed
  221. ----------
  222.  
  223.   o  The EBX register is no longer trashed intermittantly during interrupt.
  224.  
  225.   o  DMA buffer is no longer repeated during dws_Kill.
  226.  
  227.   o  Fixed a bug in a call to the Virtual DMA Services (VDS).
  228.  
  229.   o  Worked around Aztech driver bug which caused DIG to repeat/lock in Win 3.1
  230.  
  231.  
  232.  
  233. ===================
  234. New for version 2.0
  235. ===================
  236.  
  237.  
  238. Protected-Mode
  239. --------------
  240.  
  241. The STK now supports protected-mode!  Specifically, it works with the
  242. Watcom/DOS4GW (and PMODE/W) and Borland/PowerPack environments.
  243.  
  244. The protected-mode version is source-compatible with real-mode.  With the
  245. exception of such real-mode constructs as _far, real-mode STK C code _IS_
  246. protected-mode STK C code.
  247.  
  248. The core of the protected-mode STK implementation is the robust and
  249. high-quality real-mode STK kernel.  We now provide a real-mode program,
  250. STKRUN.EXE, which installs the real-mode STK kernel into residence, grabs
  251. an interrupt vector, and spawns your protected-mode application.  STKRUN.C
  252. is linked with the new version of DWS.LIB, to form STKRUN.EXE.    This program
  253. hooks a free interrupt vector, and spawns your protected-mode program.
  254. Source to it is included in the registered version.
  255.  
  256. Your protected-mode program is linked with DWSP.LIB, a 32-bit flat-model module
  257. designed to accept C calls, and pass them down to real-mode via an interrupt
  258. mechanism.  It handles all real-mode to protected-mode issues transparently to
  259. the application.
  260.  
  261. In short, you can make all STK calls as you would from real mode (there are a
  262. few restrictions, listed below).  The performance of the system is actually
  263. quite good; the calls down to real-mode don't consume much CPU time.
  264.  
  265.  
  266. Limitations
  267. -----------
  268.  
  269.   o  (new) If music is playing, any failed call to dws_MPlay will stop it.
  270.  
  271.   o  (new) dwt_ calls are NOT re-entrant in protected-mode.
  272.  
  273.   o  (old) Each digitized sound must fit in 64K (music files may be larger).
  274.  
  275.   o  (old) All actively playing sounds and music must fit in real-mode memory.
  276.  
  277.  
  278. New Errors
  279. ----------
  280.  
  281.   o  dws_NOMEM - The STK was unable to allocate sufficient real-mode memory.
  282.  
  283.   o  dws_NOTRESIDENT - The real-mode STK kernel is not resident.
  284.  
  285.  
  286.  
  287. ==============================
  288. If you're upgrading from v2.00
  289. ==============================
  290.  
  291. DSP
  292. ---
  293.  
  294. We now provide some simple DSP for pitch and volume change of DWD files.
  295. There are two important functions in dwdsp.c:
  296.  
  297.   word dwdsp_ChngVol(byte *desdwd, byte *srcdwd, word volume);
  298.   word dwdsp_ChngLen(byte *desdwd, byte *srcdwd, dword newlen);
  299.  
  300. These calls change the volume of a sound, or its pitch, respectively.
  301. Each takes a pointer to the destination buffer and the source buffer.
  302. The third parameter to dwdsp_ChngVol specifies the new volume.    0x100
  303. is identity, 0x80 is half volume, and 0x200 is twice as loud.  The
  304. third parameter to dwdsp_ChngLen is the new length, in bytes.  Making
  305. a sound longer will not only slow it down, but lower its pitch.  Making
  306. it shorter will raise the pitch.
  307.  
  308. The volume change code is mathematically correct.  The pitch code, on
  309. the other hand, is a sleazy hack which works better than it ought to.
  310. Results range from quite acceptable, to downright lousy, depending on
  311. listener expectations...
  312.  
  313. NB: You can change the volume of a sound "in place", that is pass
  314.   desdwd == srcdwd
  315. but you can NOT change length in place!
  316.  
  317. A detailed explanation of the algorithms is beyond the scope of this
  318. document, but we'll describe basically how they work.
  319.  
  320. It turns out that the volume can be changed simply by multiplying
  321. each sample by a constant.  To make a sound twice as loud, double
  322. each sample.
  323.  
  324. Pitch change is a little more complex.    The pitch of a sound depends
  325. on how fast the waveform oscillates.  dwdsp_ChngLen alters the number
  326. of samples in the sound, thereby (indirectly) determining how fast
  327. the sound will oscillate.  To make the sound longer, we're doubling
  328. (or trippling, etc.) each sample.  To make it shorter, we're simply
  329. removing samples.  This isn't the best technique, but it's fast.  It's
  330. also easy to code. <g>
  331.  
  332. This code is also a good guide to the DWD specification.
  333.  
  334. Run playdsp.exe...
  335.  
  336.  
  337. Borland Pascal Protected-Mode
  338. -----------------------------
  339.  
  340. Like for 32-bit C/C++ DOS extenders, STK support for the 16-bit DOS
  341. extender in Borland Pascal uses the real-mode program STKRUN.EXE (see
  342. above in this file, or the full documentation for more details).
  343.  
  344. Also like for 32-bit DOS extender support, the 16-bit protected-mode
  345. STK library is a wrapper which acts like an STK extender, accepting
  346. calls from your protected-mode program, thunking down to the real-mode
  347. kernel, and thunking any return values back up to protected-mode.
  348.  
  349. Unlike with the 32-bit C/C++ version, you must allocate memory beneath
  350. 1M for all sounds and songs.  The sample programs playdwd.pas and
  351. playdwm.pas use the routines in mem.pas to allocate and deallocate
  352. memory according to this requirement.
  353.  
  354. mem.pas uses DOSGlobalAlloc and DOSGlobalFree, respectively.
  355. DOSGlobalAlloc returns both a protected-mode selector and a real-mode
  356. segment.  The protected-mode STK library needs both values.  We've
  357. created a record, called dws_ADDRESS, to contain both fields.  In each
  358. case where an STK function needs the address of a sound/song buffer, it
  359. expects this structure.
  360.  
  361.  
  362. Turbo Pascal Real-Mode
  363. ----------------------
  364.  
  365. To accomodate Borland Pascal protected-mode, we've created a new record
  366. type, dws_ADDRESS.  The sample programs have been updated to use this.
  367. For real-mode code, however, dws_ADDRESS reduces to a simple pointer to
  368. byte (as we've used since version 1.0).  It's just something of which to
  369. be aware.
  370.  
  371.  
  372. Bugs Fixed
  373. ----------
  374.  
  375.   o  Fixed music looping bug (caused perceptible timing miss)
  376.  
  377.   o  Fixed sequencing bug (caused audible click in some instances)
  378.  
  379.   o  Phantom sound no longer left behind after one sequencing case
  380.  
  381.  
  382. Improvements
  383. ------------
  384.  
  385.   o  DWD data lengths no longer must be an integer number of paragraphs
  386.  
  387.   o  Added -k option to VOC2DWD.EXE to prevent paragraph alignment
  388.  
  389.   o  err.c changed; now supports dwdsp in addition to dws errors
  390.  
  391.  
  392. Corrections to Printed Manual
  393. -----------------------------
  394.  
  395.   o  The correct author for GM1.IBK is Tim Melton (not Rob Wallace)
  396.  
  397.   o  DWD specification was incorrect (the correct specification appear below)
  398.  
  399.        Byte #  Description
  400.        ------  -----------
  401.        00-22   "DiamondWare Digitized\n\0"
  402.        23      1A (EOF to abort printing of file)
  403.        24      Major version number
  404.        25      Minor version number
  405.        26-29   Unique sound ID (checksum XOR timestamp)
  406.        30      Reserved
  407.        31      Compression type (0=none)
  408.        32-33   Sampling rate (in Hz)
  409.        34      Number of channels (1=mono, 2=stereo)
  410.        35      Number of bits per sample (8, 16)
  411.        36-37   Absolute value of largest sample in file
  412.        38-41   length of data section (in bytes)
  413.        42-45   Number of samples (16-bit stereo would be 4 bytes/sample)
  414.        46-49  *Offset of data section from start of file (in bytes)
  415.        50-53   Reserved for future expansion (markers)
  416.        ??-??   Future expansion (heed the 2 offsets, above!)
  417.  
  418.  
  419. Additional Pascal Notes
  420. -----------------------
  421.  
  422. Because there are several different file formats for Pascal units, you
  423. must rename one of the files we provide before using the STK.  If you're
  424. using Turbo Pascal 6, then please rename DWS6.TPU to DWS.TPU.  For
  425. Turbo Pascal 7 (and real-mode Borland Pascal 7), rename DWS7.TPU to
  426. DWS.TPU.  For protected-mode Borland Pascal, rename DWS7.TPP to DWS.TPP.
  427.  
  428. No matter which compiler revision you're using, you'll need to compile
  429. ERR.PAS and MEM.PAS.
  430.  
  431. Don't bother trying to compile DWS.PAS.  The file is provided as a human-
  432. readable version of the unit, but it's not complete and WILL NOT COMPILE.
  433.  
  434.  
  435.  
  436. ==============================
  437. If you're upgrading from v2.20
  438. ==============================
  439.  
  440. Bugs Fixed
  441. ----------
  442.  
  443.   o  Poor clones no longer fool the STK into finding a SB-16 mixer.
  444.  
  445.   o  A rare bug causing the autodetect to terminate prematurely was fixed.
  446.  
  447.   o  The Ensoniq Soundscape PnP is now correctly identified as a SB 1.5 clone.
  448.  
  449.   o  The STK no longer second-guesses the dws_DETECTOVERRIDES struct.
  450.  
  451.  
  452. Note
  453. ----
  454.  
  455.   o  The STK was tested with the CauseWay extender (it works).
  456.  
  457.  
  458.  
  459. ==============================
  460. If you're upgrading from v2.21
  461. ==============================
  462.  
  463. Bugs Fixed
  464. ----------
  465.  
  466.   o  Worked around Windows 95 DOS box DMA buffer problems
  467.  
  468.   o  Worked around Borland PowerPak DOS-extender bug
  469.